/*
 * Copyright 2002-2005 the original author or authors.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.core.io;

import java.io.File;
import java.io.IOException;
import java.net.URL;

/**
 * #Comment#,Spring中用Resource表示一个来源无关的资源,常用来表示Spring的配置文件\国际化文件\属性文件等。<br/>
 * Interface for a resource descriptor that abstracts from the actual type of
 * underlying resource, such as a file or class path resource.
 * 
 * <p>
 * An InputStream can be opened for every resource if it exists in physical
 * form, but a URL or File handle can just be returned for certain resources.
 * The actual behavior is implementation-specific.
 * 
 * @author Juergen Hoeller
 * @since 28.12.2003
 * @see #getInputStream()
 * @see #getURL()
 * @see #getFile()
 * @see FileSystemResource
 * @see ClassPathResource
 * @see UrlResource
 * @see ByteArrayResource
 * @see InputStreamResource
 * @see org.springframework.web.context.support.ServletContextResource
 */
public interface Resource extends InputStreamSource {

	/**
	 * 此资源是否以物理形式存在<br/>
	 * Return whether this resource actually exists in physical form.
	 */
	boolean exists();

	/**
	 * 资源是否打开。<br/>
	 * Return whether this resource represents a handle with an open stream. If
	 * true, the InputStream cannot be read multiple times, and must be read and
	 * closed to avoid resource leaks.
	 * <p>
	 * Will be false for all usual resource descriptors.
	 */
	boolean isOpen();

	/**
	 * 返回此资源的URL处理器。<br/>
	 * Return a URL handle for this resource.
	 * 
	 * @throws IOException
	 *             如果资源无法被解析为URL,例如无法连接到指定的资源。<br/>
	 *             if the resource cannot be resolved as URL, i.e. if the
	 *             resource is not available as descriptor
	 */
	URL getURL() throws IOException;

	/**
	 * 返回资源的File处理器.<br/>
	 * Return a File handle for this resource.
	 * 
	 * @throws IOException
	 *             如果资源无法被解析为一个绝对文件地址，例如在一个文件系统中找不到指定的资源。<br/>
	 *             if the resource cannot be resolved as absolute file path,
	 *             i.e. if the resource is not available in a file system
	 */
	File getFile() throws IOException;

	/**
	 * Create a resource relative to this resource.
	 * 
	 * @param relativePath
	 *            the relative path (relative to this resource)
	 * @return the resource handle for the relative resource
	 * @throws IOException
	 *             if the relative resource cannot be determined
	 */
	Resource createRelative(String relativePath) throws IOException;

	/**
	 * Return a filename for this resource, i.e. typically the last part of the
	 * path: for example, "myfile.txt".
	 */
	String getFilename();

	/**
	 * Return a description for this resource, to be used for error output when
	 * working with the resource.
	 * <p>
	 * Implementations are also encouraged to return this value from their
	 * <code>toString</code> method.
	 * 
	 * @see java.lang.Object#toString
	 */
	String getDescription();

}
